metalsmith
Advanced tools
An extremely simple, pluggable static site generator for NodeJS.
In Metalsmith, all of the logic is handled by plugins. You simply chain them together.
Here's what the simplest blog looks like:
import { fileURLToPath } from 'node:url'
import { dirname } from 'path'
import Metalsmith from 'metalsmith'
import layouts from '@metalsmith/layouts'
import markdown from '@metalsmith/markdown'
const __dirname = dirname(fileURLToPath(import.meta.url))
Metalsmith(__dirname)
.use(markdown())
.use(
layouts({
pattern: '**/*.html'
})
)
.build(function (err) {
if (err) throw err
console.log('Build finished!')
})
NPM:
npm install metalsmith
Yarn:
yarn add metalsmith
What if you want to get fancier by hiding unfinished drafts, grouping posts in collections, and using custom permalinks? Just add plugins...
import { fileURLToPath } from 'node:url'
import { dirname } from 'node:path'
import Metalsmith from 'metalsmith'
import collections from '@metalsmith/collections'
import layouts from '@metalsmith/layouts'
import markdown from '@metalsmith/markdown'
import permalinks from '@metalsmith/permalinks'
import drafts from '@metalsmith/drafts'
const __dirname = dirname(fileURLToPath(import.meta.url))
const t1 = performance.now()
const devMode = process.env.NODE_ENV === 'development'
Metalsmith(__dirname) // parent directory of this file
.source('./src') // source directory
.destination('./build') // destination directory
.clean(true) // clean destination before
.env({
// pass NODE_ENV & other environment variables
DEBUG: process.env.DEBUG,
NODE_ENV: process.env.NODE_ENV
})
.metadata({
// add any variable you want & use them in layout-files
sitename: 'My Static Site & Blog',
siteurl: 'https://example.com/',
description: "It's about saying »Hello« to the world.",
generatorname: 'Metalsmith',
generatorurl: 'https://metalsmith.io/'
})
.use(drafts(devMode)) // only include drafts when NODE_ENV === 'development'
.use(
collections({
// group all blog posts by adding key
posts: 'posts/*.md' // collections:'posts' to metalsmith.metadata()
})
) // use `collections.posts` in layouts
.use(
markdown({
// transpile all md file contents into html
keys: ['description'], // and also file.description
globalRefs: {
// define links available to all markdown files
home: 'https://example.com'
}
})
)
.use(permalinks()) // change URLs to permalink URLs
.use(
layouts({
// wrap layouts around html
pattern: '**/*.html'
})
)
.build((err) => {
// build process
if (err) throw err // error handling is required
console.log(`Build success in ${((performance.now() - t1) / 1000).toFixed(1)}s`)
})
Metalsmith works in three simple steps:
Each plugin is invoked with the contents of the source directory, and each file can contain YAML front-matter that will be attached as metadata, so a simple file like...
---
title: A Catchy Title
date: 2024-01-01
---
An informative article.
...would be parsed into...
{
'path/to/my-file.md': {
title: 'A Catchy Title',
date: new Date(2024, 1, 1),
contents: Buffer.from('An informative article'),
stats: fs.Stats
}
}
...which any of the plugins can then manipulate however they want. Writing plugins is incredibly simple, just take a look at the example drafts plugin.
Of course they can get a lot more complicated too. That's what makes Metalsmith powerful; the plugins can do anything you want!
A Metalsmith plugin is a function that is passed the file list, the metalsmith instance, and a done callback. It is often wrapped in a plugin initializer that accepts configuration options.
Check out the official plugin registry at: https://metalsmith.io/plugins.
Find all the core plugins at: https://github.com/search?q=org%3Ametalsmith+metalsmith-plugin
See the draft plugin for a simple plugin example.
Check out the full API reference at: https://metalsmith.io/api.
In addition to a simple Javascript API, the Metalsmith CLI can read configuration from a metalsmith.json file, so that you can build static-site generators similar to Jekyll or Hexo easily. The example blog above would be configured like this:
metalsmith.json
{
"source": "src",
"destination": "build",
"clean": true,
"metadata": {
"sitename": "My Static Site & Blog",
"siteurl": "https://example.com/",
"description": "It's about saying »Hello« to the world.",
"generatorname": "Metalsmith",
"generatorurl": "https://metalsmith.io/"
},
"plugins": [
{ "@metalsmith/drafts": true },
{ "@metalsmith/collections": { "posts": "posts/*.md" } },
{ "@metalsmith/markdown": true },
{ "@metalsmith/permalinks": "posts/:title" },
{ "@metalsmith/layouts": true }
]
}
Then run:
metalsmith
# Metalsmith · reading configuration from: /path/to/metalsmith.json
# Metalsmith · successfully built to: /path/to/build
Options recognised by metalsmith.json are source, destination, concurrency, metadata, clean and frontmatter.
Checkout the static site, Jekyll examples to see the CLI in action.
If you want to use a custom plugin, but feel like it's too domain-specific to be published to the world, you can include plugins as local npm modules: (simply use a relative path from your root directory)
{
"plugins": [{ "./lib/metalsmith/plugin.js": true }]
}
We often refer to Metalsmith as a "static site generator", but it's a lot more than that. Since everything is a plugin, the core library is just an abstraction for manipulating a directory of files.
Which means you could just as easily use it to make...
Set metalsmith.env('DEBUG', '*metalsmith*') to debug your build. This will log debug logs for all plugins using the built-in metalsmith.debug debugger.
For older plugins using debug directly, run your build with export DEBUG=metalsmith-*,@metalsmith/* (Linux) or set DEBUG=metalsmith-*,@metalsmith/* for Windows.
Future Metalsmith releases will at least support the oldest supported Node LTS versions.
Metalsmith 2.6.x supports NodeJS versions 14.18.0 and higher.
Metalsmith 2.5.x supports NodeJS versions 12 and higher.
Metalsmith 2.4.x supports NodeJS versions 8 and higher.
Metalsmith 2.3.0 and below support NodeJS versions all the way back to 0.12.
Metalsmith is supported on all common operating systems (Windows, Linux, Mac). Metalsmith releases adhere to semver (semantic versioning) with 2 minor gray-area exceptions for what could be considered breaking changes:
Special thanks to Ian Storm Taylor, Andrew Meyer, Dominic Barnes, Andrew Goodricke, Ismay Wolff, Kevin Van Lierde and others for their contributions!
[2.6.3] - 2024-03-05
b170cf0774a164
chokidar: 3.5.3 ▶︎ 3.6.00d8d791FAQs
An extremely simple, pluggable static site generator.
The npm package metalsmith receives a total of 9,502 weekly downloads. As such, metalsmith popularity was classified as popular.
We found that metalsmith demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 5 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
Security News
Socket researchers uncover a malicious npm package posing as a tool for detecting vulnerabilities in Etherium smart contracts.
Security News
Research
A supply chain attack on Rspack's npm packages injected cryptomining malware, potentially impacting thousands of developers.
Research
Security News
Socket researchers discovered a malware campaign on npm delivering the Skuld infostealer via typosquatted packages, exposing sensitive data.